---
title: 'children | Cypress Documentation'
description: Get the children of each DOM element within a set of DOM elements in Cypress.
sidebar_label: children
slug: /api/commands/children
---

<ProductHeading product="app" />

# children

Get the children of each DOM element within a set of DOM elements.

:::info

The querying behavior of this command matches exactly how
[`.children()`](http://api.jquery.com/children) works in jQuery.

:::

## Syntax

```javascript
.children()
.children(selector)
.children(options)
.children(selector, options)
```

### Usage

<Icon name="check-circle" color="green" /> **Correct Usage**

```javascript
cy.get('nav').children() // Yield children of nav
```

<Icon name="exclamation-triangle" color="red" /> **Incorrect Usage**

```javascript
cy.children() // Errors, cannot be chained off 'cy'
cy.clock().children() // Errors, 'clock' does not yield DOM elements
```

### Arguments

<Icon name="angle-right" /> **selector _(String selector)_**

A selector used to filter matching DOM elements.

<Icon name="angle-right" /> **options _(Object)_**

Pass in an options object to change the default behavior of `.children()`.

| Option    | Default                                                           | Description                                                                         |
| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `log`     | `true`                                                            | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log) |
| `timeout` | [`defaultCommandTimeout`](/app/references/configuration#Timeouts) | Time to wait for `.children()` to resolve before [timing out](#Timeouts)            |

<HeaderYields />

- `.children()` yields the new DOM element(s) it found.
- `.children()` is a query, and it is _safe_ to chain further commands.

## Examples

### No Args

#### Get the children of the `.secondary-nav`

```html
<ul>
  <li>About</li>
  <li>
    Services
    <ul class="secondary-nav">
      <li class="services-1">Web Design</li>
      <li class="services-2">Logo Design</li>
      <li class="services-3">
        Print Design
        <ul class="tertiary-nav">
          <li>Signage</li>
          <li>T-Shirt</li>
          <li>Business Cards</li>
        </ul>
      </li>
    </ul>
  </li>
  <li>Contact</li>
</ul>
```

```javascript
// yields [
//  <li class="services-1">Web Design</li>,
//  <li class="services-2">Logo Design</li>,
//  <li class="services-3">Print Design</li>
// ]
cy.get('ul.secondary-nav').children()
```

### Selector

#### Get the children with class `active`

```html
<div>
  <ul>
    <li class="active">Unit Testing</li>
    <li>Integration Testing</li>
  </ul>
</div>
```

```javascript
// yields [
//  <li class="active">Unit Testing</li>
// ]
cy.get('ul').children('.active')
```

## Rules

<HeaderRequirements />

- `.children()` requires being chained off a command that yields DOM element(s).

<HeaderAssertions />

- `.children()` will automatically [retry](/app/core-concepts/retry-ability)
  until the element(s)
  [exist in the DOM](/app/core-concepts/introduction-to-cypress#Implicit-Assertions).
- `.children()` will automatically [retry](/app/core-concepts/retry-ability)
  until all chained assertions have passed.

<HeaderTimeouts />

- `.children()` can time out waiting for the element(s) to
  [exist in the DOM](/app/core-concepts/introduction-to-cypress#Implicit-Assertions).
- `.children()` can time out waiting for assertions you've added to pass.

## Command Log

**_Assert that there should be 8 children elements in a nav_**

```javascript
cy.get('.left-nav>.nav').children().should('have.length', 8)
```

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/children/children-elements-shown-in-command-log.png"
  alt="Command log for children"
/>

When clicking on the `children` command within the command log, the console
outputs the following:

<DocsImage
  src="/img/api/children/children-yielded-in-console.png"
  alt="console.log for children"
/>

## See also

- [`.next()`](/api/commands/next)
- [`.parent()`](/api/commands/parent)
- [`.parents()`](/api/commands/parents)
- [`.siblings()`](/api/commands/siblings)
